/*
 * Copyright 2002-2022 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.expression.spel.ast;

import java.lang.reflect.Array;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Map;

import org.springframework.expression.EvaluationException;
import org.springframework.expression.TypedValue;
import org.springframework.expression.spel.ExpressionState;
import org.springframework.expression.spel.SpelEvaluationException;
import org.springframework.expression.spel.SpelMessage;
import org.springframework.lang.Nullable;
import org.springframework.util.ClassUtils;
import org.springframework.util.ObjectUtils;

/**
 * pojection 在 SpEL 中是指一种操作，它允许你对集合类型（如列表、数组或映射）执行投影操作，
 * 即对集合中的每个元素应用一个表达式，并返回一个新的集合，其中包含应用表达式后得到的结果。
 *
 * Projection 的概念
 * 		投影操作：类似于 SQL 查询中的 SELECT 子句或者 Java 8 Stream API 中的 map 操作。你可以指定一个表达式，该表达式将应用于集合中的每一个元素，生成一个新的结果集合。
 * 		使用场景：当你需要对集合进行转换，比如提取集合中对象的特定属性，或者对集合中的每个元素执行某种计算时，投影操作是非常有用的。
 *
 * 使用例子
 * 		示例 1：从列表中提取属性
 * 		假设我们有一个用户列表，每个用户都有一个名字和年龄。我们可以使用 SpEL 的投影功能来提取所有用户的姓名：
 *
 * 		import org.springframework.expression.ExpressionParser;
 * 		import org.springframework.expression.spel.standard.SpelExpressionParser;
 * 		import org.springframework.expression.spel.support.StandardEvaluationContext;
 *
 * 		public class SpelProjectionExample {
 *
		 *     public static void main(String[] args) {
		 *         // 创建解析器
		 *         ExpressionParser parser = new SpelExpressionParser();
		 *
		 *         // 创建上下文并设置根对象
		 *         StandardEvaluationContext context = new StandardEvaluationContext();
		 *
		 *         // 创建用户列表
		 *         List<User> users = Arrays.asList(
		 *             new User("Alice", 30),
		 *             new User("Bob", 25),
		 *             new User("Charlie", 35)
		 *         );
		 *
		 *         // 设置用户列表到上下文中
		 *         context.setVariable("users", users);
		 *
		 *         // 解析并评估投影表达式
		 *         String expression = "users.![name]";
		 *         List<String> result = parser.parseExpression(expression).getValue(context, List.class);
		 *
		 *         System.out.println(result); // 输出: [Alice, Bob, Charlie]
		 *     }
		 *
		 *     static class User {
		 *         private String name;
		 *         private int age;
		 *
		 *         public User(String name, int age) {
		 *             this.name = name;
		 *             this.age = age;
		 *         }
		 *
		 *         public String getName() {
		 *             return name;
		 *         }
		 *
		 *         public int getAge() {
		 *             return age;
		 *         }
		 *     }
		 * }
 *
 * 在这个例子中，users.![name] 是一个投影表达式，它会遍历 users 列表中的每个 User 对象，并提取其 name 属性，最终返回一个新的字符串列表。
 *
 * 示例 2：对集合元素进行计算
 * 	除了提取属性，投影还可以用来对集合中的每个元素执行某些计算。例如，如果我们想获取所有用户的年龄加一后的结果：
 *			// 解析并评估投影表达式
 * 		String expression = "users.![age + 1]";
 * 		List<Integer> result = parser.parseExpression(expression).getValue(context, List.class);
 * 		System.out.println(result); // 输出: [31, 26, 36]
 *
 *	这里，users.![age + 1] 表达式对 users 列表中的每个 User 对象的 age 属性进行了加一操作，并返回了一个新的整数列表。
 *
 * 示例 3：结合条件筛选
 * 		投影操作可以与选择（Selection）操作结合起来使用。例如，如果我们只想提取年龄大于 30 岁的用户的姓名：
 *
 *	示例 3：结合条件筛选
 * 投影操作可以与选择（Selection）操作结合起来使用。例如，如果我们只想提取年龄大于 30 岁的用户的姓名：
 * 这里，users.?[age > 30] 是一个选择表达式，它首先过滤出年龄大于 30 的用户，然后 .![name] 投影表达式提取这些用户的姓名。
 *
 *
 * <br>
 *
 * Represents projection, where a given operation is performed on all elements in some
 * input sequence, returning a new sequence of the same size. For example:
 * "{1,2,3,4,5,6,7,8,9,10}.!{#isEven(#this)}" returns "[n, y, n, y, n, y, n, y, n, y]"
 *
 * <br> 代表投影，其中对某些输入序列中的所有元素执行给定的操作，返回与原始序列大小相同的新的序列。例如："{1,2,3,4,5,6,7,8,9,10}.!{#isEven(#this)}"
 *
 * @author Andy Clement
 * @author Mark Fisher
 * @author Juergen Hoeller
 * @since 3.0
 */
public class Projection extends SpelNodeImpl {

	private final boolean nullSafe;


	public Projection(boolean nullSafe, int startPos, int endPos, SpelNodeImpl expression) {
		super(startPos, endPos, expression);
		this.nullSafe = nullSafe;
	}


	@Override
	public TypedValue getValueInternal(ExpressionState state) throws EvaluationException {
		return getValueRef(state).getValue();
	}

	@Override
	protected ValueRef getValueRef(ExpressionState state) throws EvaluationException {
		TypedValue op = state.getActiveContextObject();

		Object operand = op.getValue();
		boolean operandIsArray = ObjectUtils.isArray(operand);
		// TypeDescriptor operandTypeDescriptor = op.getTypeDescriptor();

		// When the input is a map, we push a special context object on the stack
		// before calling the specified operation. This special context object
		// has two fields 'key' and 'value' that refer to the map entries key
		// and value, and they can be referenced in the operation
		// eg. {'a':'y','b':'n'}.![value=='y'?key:null]" == ['a', null]
		if (operand instanceof Map<?, ?> mapData) {
			List<Object> result = new ArrayList<>();
			for (Map.Entry<?, ?> entry : mapData.entrySet()) {
				try {
					state.pushActiveContextObject(new TypedValue(entry));
					state.enterScope();
					result.add(this.children[0].getValueInternal(state).getValue());
				}
				finally {
					state.popActiveContextObject();
					state.exitScope();
				}
			}
			return new ValueRef.TypedValueHolderValueRef(new TypedValue(result), this);  // TODO unable to build correct type descriptor
		}

		if (operand instanceof Iterable || operandIsArray) {
			Iterable<?> data = (operand instanceof Iterable<?> iterable ?
					iterable : Arrays.asList(ObjectUtils.toObjectArray(operand)));

			List<Object> result = new ArrayList<>();
			Class<?> arrayElementType = null;
			for (Object element : data) {
				try {
					state.pushActiveContextObject(new TypedValue(element));
					state.enterScope("index", result.size());
					Object value = this.children[0].getValueInternal(state).getValue();
					if (value != null && operandIsArray) {
						arrayElementType = determineCommonType(arrayElementType, value.getClass());
					}
					result.add(value);
				}
				finally {
					state.exitScope();
					state.popActiveContextObject();
				}
			}

			if (operandIsArray) {
				if (arrayElementType == null) {
					arrayElementType = Object.class;
				}
				Object resultArray = Array.newInstance(arrayElementType, result.size());
				System.arraycopy(result.toArray(), 0, resultArray, 0, result.size());
				return new ValueRef.TypedValueHolderValueRef(new TypedValue(resultArray),this);
			}

			return new ValueRef.TypedValueHolderValueRef(new TypedValue(result),this);
		}

		if (operand == null) {
			if (this.nullSafe) {
				return ValueRef.NullValueRef.INSTANCE;
			}
			throw new SpelEvaluationException(getStartPosition(), SpelMessage.PROJECTION_NOT_SUPPORTED_ON_TYPE, "null");
		}

		throw new SpelEvaluationException(getStartPosition(), SpelMessage.PROJECTION_NOT_SUPPORTED_ON_TYPE,
				operand.getClass().getName());
	}

	@Override
	public String toStringAST() {
		return "![" + getChild(0).toStringAST() + "]";
	}

	private Class<?> determineCommonType(@Nullable Class<?> oldType, Class<?> newType) {
		if (oldType == null) {
			return newType;
		}
		if (oldType.isAssignableFrom(newType)) {
			return oldType;
		}
		Class<?> nextType = newType;
		while (nextType != Object.class) {
			if (nextType.isAssignableFrom(oldType)) {
				return nextType;
			}
			nextType = nextType.getSuperclass();
		}
		for (Class<?> nextInterface : ClassUtils.getAllInterfacesForClassAsSet(newType)) {
			if (nextInterface.isAssignableFrom(oldType)) {
				return nextInterface;
			}
		}
		return Object.class;
	}

}
